NOM¶

distcc - Compilateur C/C++/ObjC réparti

SYNOPSIS¶

distcc <compilateur> [OPTIONS DU COMPILATEUR]

distcc [OPTIONS DU COMPILATEUR]

<compilateur> [OPTIONS DU COMPILATEUR]

DESCRIPTION¶

distcc répartit la compilation de code C entre plusieurs machines en réseau. A priori, distcc génère toujours les mêmes exécutables qu'un compilateur local ; il est simple à installer et à utiliser ; enfin il est souvent bien plus rapide qu'un compilateur local.

Pour chaque tâche de la construction, distcc envoie tout le code source prétraité et les paramètres de compilation sur le réseau : les machines n'ont donc besoin ni de partager de système de fichiers, ni d'avoir les mêmes en-têtes ou bibliothèques installés, ni d'une horloge synchronisée.

La compilation est pilotée par une machine « client » : typiquement la station de travail ou le portable du développeur. Le client distcc s'exécute sur cette machine, tout comme make, le préprocesseur, l'éditeur de liens et les autres étapes du processus de construction. Les machines « volontaires », sans limitation de nombre, aident le client à construire le programme en exécutant le démon distccd(1), le compilateur et l'assembleur à la demande.

distcc peut être exécuté soit en utilisant des sockets TCP (sur le port 3632 par défaut), soit par une commande « tunnel » telle que ssh(1). Pour utiliser les connexions TCP, les clients doivent exécuter le démon distccd(1) directement ou à partir d'inetd. Pour les connexions SSH, distcc doit être installé mais ne doit pas rester à l'écoute en attente de connexions.

Les connexions TCP ne doivent être utilisées que sur un réseau digne de confiance, car les codes source et objet ne sont ni authentifiés ni protégés. Les connexions SSH sont typiquement plus lentes de 25 % en raison de la charge supplémentaire liée au chiffrement, bien que ce rapport varie beaucoup suivant le processeur, le réseau et le programme construit.

distcc est conçu pour être utilisé avec l'option -j de GNU Make, qui effectue plusieurs compilations simultanément. Puisque distcc peut répartir la plus grande partie du travail sur le réseau, le niveau de concurrence atteint est plus grand que lors d'une construction locale. On fixe normalement la valeur de l'option -j à peu près au double du nombre de processeurs disponibles, afin de permettre à certaines tâches de rester bloquées en attente d'E/S disque ou réseau. distcc peut également être utilisé avec d'autres outils de contrôle de construction tels que SCons.

Il est fortement recommandé d'installer la même version du compilateur sur chaque machine participant à la construction. Des compilateurs incompatibles peuvent causer des erreurs de compilation ou d'édition des liens difficiles à identifier.

DÉMARRAGE RAPIDE¶

1

Sur chaque machine : téléchargez distcc, décompressez-le, et installez-le ;

2

Sur chaque serveur, exécutez distccd --daemon avec l'option --allow pour restreindre l'accès ;

3

Placez les noms des serveurs dans votre environnement :

4

Lancez la construction !

FONCTIONNEMENT¶

distcc ne répartit que les tâches de compilation et d'assemblage. Le préprocesseur doit toujours s'exécuter localement car il doit accéder à divers fichiers d'en-tête sur la machine locale qui pourraient être absents ou différents sur la machine volontaire. De même, l'éditeur de liens doit examiner les bibliothèques et les fichiers objets, et doit donc s'exécuter localement.

Le compilateur et l'assembleur attendent un seul fichier en entrée (le code source prétraité) et produisent un seul fichier en sortie (le fichier objet). distcc expédie ces deux fichiers sur le réseau et peut ainsi exécuter la compilation ou l'assemblage à distance.

Heureusement, pour la majorité des programmes l'exécution du préprocesseur est relativement peu coûteuse et l'éditeur de liens n'est pas appelé souvent, donc la plus grande partie du travail peut être distribuée.

distcc examine sa ligne de commande pour déterminer laquelle de ces phases est invoquée, et si la tâche peut être distribuée.

RÉSUMÉ DES OPTIONS¶

La plupart des options passées à distcc sont interprétées comme des options du compilateur. Deux options sont comprises par distcc lui-même :

--help

Affiche un résumé des commandes disponibles.

--version

Affiche la version du client distcc.

INSTALLATION DE DISTCC¶

Il y a trois manières d'appeler distcc, qui correspondent à différentes circonstances :

Gardez à l'esprit que vous ne devez utiliser qu'une seule méthode à la fois pour appeler distcc. Si vous utilisez un répertoire de masquage, ne changez pas CC ou CXX : indiquez simplement le répertoire vers le début de votre chemin de recherche (« PATH »). Si vous n'utilisez pas de répertoire de masquage, vous devrez soit changer CC ou CXX, soit modifier le(s) makefile(s) pour qu'il(s) appelle(nt) distcc explicitement.

MASQUAGE¶

Le principe est de créer un « répertoire de masquage » qui contient des liens portant le nom du vrai compilateur et pointant vers l'exécutable de distcc. Ce répertoire est inséré vers le début du chemin de recherche (« PATH »), afin que les appels au compilateur soient interceptés et que distcc soit exécuté à sa place. distcc se retire alors lui-même du chemin de recherche et trouve le vrai compilateur.

Par exemple :

# mkdir /usr/lib/distcc/bin
# cd /usr/lib/distcc/bin
# ln -s ../../../bin/distcc gcc
# ln -s ../../../bin/distcc cc
# ln -s ../../../bin/distcc g++
# ln -s ../../../bin/distcc c++

Ainsi, pour utiliser distcc, un utilisateur doit simplement placer le répertoire /usr/lib/distcc/bin vers le début du chemin de recherche, et fixer une liste d'hôtes dans DISTCC_HOSTS ou dans un fichier. distcc se charge du reste.

Notez que le répertoire de masquage doit se trouver dans le chemin de recherche avant le répertoire contenant le compilateur dont il porte le nom. De plus, tous les programmes auxiliaires que ce compilateur utilise (tels que as ou ld) doivent également se trouver dans un répertoire cité après le répertoire de masquage dans le chemin de recherche. En effet, distcc appelle le vrai compilateur avec un chemin de recherche dont sont retirés tous les répertoires jusqu'au répertoire de masquage inclus.

Il est possible de rencontrer une « erreur de récursion » dans le mode masqué, ce qui signifie que distcc se trouve lui-même plutôt que de trouver le vrai compilateur. Cela peut indiquer que deux répertoires de masquage sont indiqués dans le chemin de recherche, peut-être à cause de l'installation de distcc à deux emplacements différents. Cela peut également indiquer que vous tentez de mélanger le mode « masqué » et le mode « explicite ».

UTILISATION DE DISTCC AVEC CCACHE¶

ccache est un programme qui accélère la construction des logiciels en conservant en cache le résultat des compilations. ccache est normalement appelé avant distcc, afin que les résultats soient tirés d'un cache normal.

Le moyen le plus simple d'utiliser ccache avec distcc est de créer un répertoire de masquage pour chacun d'eux, et de lister le répertoire de ccache avant celui de distcc. Par exemple :

Une autre solution consiste à fixer CCACHE_PREFIX=distcc et à utiliser CC="ccache gcc" .

Depuis la version 2.2, ccache ne conserve plus la compilation des sources prétraités, donc il ne trouvera jamais de correspondance dans le cache s'il est exécuté depuis distccd ou distcc. Il ne doit être exécuté que sur le client et avant distcc pour être efficace.

SPÉCIFICATIONS D'HÔTES¶

Une « liste d'hôtes » indique à distcc quelles machines utiliser pour la compilation. distcc consulte, dans l'ordre : la variable d'environnement $DISTCC_HOSTS ; le fichier ~/.distcc/hosts de l'utilisateur ; puis le fichier d'hôtes du système. Si distcc ne trouve aucune liste d'hôtes, il émet un avertissement et effectue les compilations localement.

La liste d'hôtes est une simple énumération de spécifications d'hôtes séparées par des espaces. La forme la plus simple et la plus courante est l'énumération de noms d'hôtes, telle que

distcc accorde une préférence aux hôtes cités en début de liste, aussi les machines doivent être citées par ordre décroissant de vitesse. En particulier, lorsqu'une seule compilation doit être exécutée (par exemple depuis un script « configure »), la première machine de la liste est utilisée. Du fait de la faible surcharge entraînée par l'exécution des tâches locales, localhost doit normalement être la première. Si le client est largement plus lent que les autres machines (cas d'un ordinateur de poche par exemple), on peut le citer plus loin dans la liste, voire pas du tout.

La syntaxe est :

  DISTCC_HOSTS = SPEC_HÔTE ...


  HOSTSPEC = HÔTE_LOCAL | HÔTE_SSH | HÔTE_TCP | HÔTE_TCP_ANCIENSTYLE


  LOCAL_HOST = localhost[/LIMITE]


  SSH_HOST = [UTILISATEUR]@IDHÔTE[/LIMITE][:COMMANDE][OPTIONS]


  TCP_HOST = IDHÔTE[:PORT][/LIMITE][OPTIONS]


  OLDSTYLE_TCP_HOST = IDHÔTE[/LIMITE][:PORT][OPTIONS]


  HOSTID = NOMHÔTE | IPV4


  OPTIONS = ,OPTION[OPTIONS]


  OPTION = lzo

Voici quelques exemples de cette syntaxe :

localhost

Le mot réservé « localhost » est interprété spécifiquement et impose que les compilations soient exécutées directement, plutôt que d'être passées au démon sur la machine locale. Si vous désirez effectivement vous connecter au démon de la machine locale pour effectuer des tests (ce qui sera plus lent), indiquez l'adresse IP de la machine ou son véritable nom d'hôte.

IPV4

Une adresse IPv4 littérale, telle que 10.0.0.1

NOMHÔTE

Un nom d'hôte qui sera résolu par le serveur de noms.

:PORT

Établit la connexion au port indiqué en décimal, plutôt qu'au port par défaut 3632.

@HOTID

Établit la connexion sur SSH plutôt que sur TCP. Les options concernant la connexion SSH peuvent être fixées dans ~/.ssh/config

UTILISATEUR@

Établit la connexion sur SSH sous le nom d'utilisateur indiqué.

:COMMANDE

Établit la connexion sur SSH, et utilise le chemin indiqué pour trouver le serveur distccd. Ce n'est normalement nécessaire que si vous ne pouvez pas installer distccd dans un répertoire du chemin de recherche (« PATH ») des connexions SSH. Utilisez cette option si vous rencontrez des erreurs du type « distccd : commande introuvable » en mode SSH.

/LIMITE

Une limite décimale peut être ajoutée à chaque spécification d'hôte afin de restreindre le nombre de tâches que le client enverra à cette machine. Cette limite est fixée par défaut à quatre tâches par hôte, mais peut être encore réduite par le serveur. Vous ne devriez avoir à augmenter cette valeur que pour les serveurs dotés de plus de deux processeurs.

,lzo

Active la compression LZO pour cet hôte TCP ou SSH.

Voici un exemple illustrant certaines de ces possibilités :

Si un hôte de la liste n'est pas joignable distcc émet un avertissement et ignore cet hôte pendant environ une minute.

COMPRESSION¶

L'option d'hôte lzo indique que la compression LZO doit être utilisée pour les transferts de données : code source prétraité, code objet et messages d'erreur. La compression est généralement économique sur les réseaux dont le débit est inférieur à 100 Mb/s, mais les résultats peuvent varier selon le réseau, les processeurs et l'arborescence source.

Activer la compression fait consommer plus de temps CPU par distcc, mais moins de trafic réseau. Le taux de compression est typiquement de 4/1 pour le code source et 2/1 pour le code objet.

L'utilisation de la compression exige que le client et le serveur utilisent tous deux la version 2.9 de distcc ou une version plus récente. Aucune configuration du serveur n'est nécessaire : le serveur répond toujours à des requêtes compressées par des réponses compressées.

DIAGNOSTIC¶

Les messages d'erreur ou les avertissements des compilateurs locaux ou distants sont transférés à la sortie de diagnostic du client.

distcc peut fournir des informations de débogage détaillées si l'option « verbose » est employée. On la contrôle grâce à la variable d'environnement DISTCC_VERBOSE sur le client, et grâce à l'option --verbose sur le serveur. Pour corriger les erreurs, vous devez examiner aussi bien les messages du client que ceux des serveurs.

CODES DE SORTIE¶

Le code de sortie de distcc est normalement celui du compilateur : zéro pour une compilation menée à bien, non nul sinon.

distcc distingue les erreurs « authentiques », telles que les erreurs de syntaxe dans le code source, des erreurs « accidentelles », telles que les problèmes de réseau rencontrés lors de la connexion à une machine volontaire. Dans le cas d'une erreur accidentelle, distcc réessayera la connexion en local à moins que l'option DISTCC_FALLBACK n'ait été désactivée.

Si le compilateur se termine avec un signal, distcc retourne un code de sortie égal à 128 plus le numéro du signal.

Les erreurs internes de distcc provoquent des codes de sortie entre 100 et 127. En particulier :

100

Échec général de distcc ;

105

Mémoire saturée ;

110

Compilateur introuvable ;

111

Appel récursif à distcc ;

116

Aucun hôte défini et repli (« fallback ») désactivé.

(D'autres codes d'erreur sont listés dans exitcode.h)

FICHIERS¶

Si $DISTCC_HOSTS n'est pas défini, distcc lit une liste d'hôtes soit dans ~/.distcc/hosts , soit dans un fichier système défini lors de sa compilation. L'emplacement de ce fichier est affiché parmi les informations données par distcc --help

distcc crée un certain nombre de fichiers temporaires et de fichiers de verrouillage dans le répertoire temporaire.

VARIABLES D'ENVIRONNEMENT¶

Le comportement de distcc est contrôlé par un certain nombre de variables d'environnement. Dans la plupart des cas, rien n'a besoin d'être défini si la liste d'hôtes est stockée dans un fichier.

DISTCC_HOSTS

Liste de spécifications d'hôtes, séparées par des espaces.

DISTCC_VERBOSE

Si cette valeur est fixée à 1, distcc produit un message d'explication sur le flux d'erreur standard ou dans le fichier-journal. Cela peut être utile face à des problèmes de débogage. Les rapports de bogue doivent contenir ce type de message.

DISTCC_LOG

Fichier-journal destiné à recevoir les messages de distcc lui-même à la place de stderr.

DISTCC_FALLBACK

Par défaut, distcc exécute les compilations en local s'il ne parvient pas à distribuer les tâches correspondantes aux machines voulues, ou si aucun hôte n'est trouvable. Si cette valeur est fixée à 0, le repli (« fallback ») est désactivé et ces compilations sont simplement abandonnées. Notez que cela n'affecte pas les tâches qui doivent toujours s'exécuter en local telles que l'édition des liens.

DISTCC_SAVE_TEMPS

Si cette valeur est fixée à 1, les fichiers temporaires sont conservés après utilisation. Utile pour le débogage, ou si vous avez trop de place sur vos disques.

DISTCC_TCP_CORK

Si cette valeur est fixée à 0, désactive l'utilisation des « bouchons TCP » (« TCP corks »). L'utilisation des bouchons TCP permet de regrouper plusieurs requêtes en un nombre réduit de paquets, ce qui améliore les performances. Elle devrait rester activée.

DISTCC_SSH

Précise la commande à utiliser pour ouvrir une connexion SSH. La valeur par défaut est « ssh » mais elle peut être fixée à une autre commande de connexion telle que « lsh » ou « tsocks-ssh », qui acceptent des lignes de commandes similaires. La commande n'est pas scindée en mots et n'est pas exécutée à travers l'interpréteur de commande (« shell »).

TMPDIR

Répertoire temporaire du système. distcc crée un sous-répertoire dont le nom comprend le nom d'hôte et l'identifiant de l'utilisateur pour y stocker tous ses fichiers. Par défaut, /tmp/ est utilisé.

UNCACHED_ERR_FD

Lorsque cette variable est définie et que DISTCC_LOG n'est pas définie, les erreurs rencontrées par distcc sont inscrites dans le descripteur de fichier identifié par cette variable. Cette option permet aux erreurs passagères telles que les erreurs liées au réseau de ne pas être placées en cache par ccache.

COMPILATION CROISÉE¶

Effectuer une compilation croisée consiste à construire un programme destiné à s'exécuter sur un autre processeur, une autre architecture, ou un autre système d'exploitation que ceux sur lequel il a été compilé. distcc accepte la compilation croisée, y compris l'utilisation de machines d'architectures différentes, bien que certains changements aux lignes de commandes de compilation puissent être nécessaires.

La commande de compilation passée à distcc doit être apte à s'exécuter correctement sur chacune des machines volontaires pour produire un fichier objet du type approprié. Si les machines ont des processeurs différents, la simple utilisation de distcc cc ne fonctionnera probablement pas, car cela lancera normalement le compilateur natif de la machine volontaire.

Des machines ayant le même processeur mais des systèmes d'exploitation différents ne génèrent pas nécessairement des fichiers .o compatibles.

Plusieurs configurations différentes de gcc peuvent être installées côte-à-côte sur une machine. Si vous construisez gcc à partir du code source, utilisez l'option de configuration --program-suffix afin qu'il soit installé sous un nom qui contienne la version de gcc et la plate-forme cible.

La convention recommandée pour le nom de gcc est CIBLE-gcc-VERSION (par exemple : i686-linux-gcc-3.2 ). GCC 3.3 s'installera de lui-même sous ce nom, en complément de CIBLE-gcc et, s'il est adapté à la machine locale, de gcc-VERSION et de gcc .

Le compilateur doit être installé sous le même nom sur le client et sur chaque machine volontaire.

BOGUES¶

Si vous pensez avoir rencontré un bogue dans distcc, merci de vous reporter au fichier reporting-bugs.txt dans le répertoire de la documentation pour toute information sur la manière de le rapporter.

Du fait d'une limitation de gcc, gdb peut être incapable de trouver automatiquement les fichiers sources des programmes construits en utilisant distcc dans certaines circonstances. La commande directory de gdb peut être utilisée à cet effet.

L'option -MD de gcc peut produire une sortie dans un mauvais répertoire si les fichiers source et objet sont dans des répertoires différents et que l'option -MF n'est pas utilisée. Il n'y a pas de solution parfaite en raison de changements incompatibles entre les versions de gcc. Indiquer explicitement le fichier de sortie de dépendance avec l'option -MF résoudra ce problème.

Le mode de connexion TCP ne doit être utilisé que sur les réseaux dignes de confiance.

Inscrire des machines lentes dans la liste des machines volontaires peut ralentir la construction.

Utiliser des versions de gcc différentes peut provoquer des problèmes car les fichiers d'en-tête et les interfaces binaires ont évolué, et de plus certaines distributions ont inclus des correctifs incompatibles sans changer le numéro de version. distcc n'offre aucune protection contre l'utilisation de versions incompatibles.

Certains makefiles ont des dépendances manquantes ou superflues qui provoquent des constructions en parallèle incorrectes ou lentes. Réparez le makefile en corrigeant les dépendances, rapportez le bogue au responsable du logiciel, ou ne construisez pas l'arborescence en parallèle.

D'autres bogues connus peuvent être documentés à l'adresse http://distcc.samba.org/

AUTEUR¶

distcc a été écrit par Martin Pool <mbp@sourcefrog.net>, avec la coopération de nombreux érudits dont Wayne Davison, Frerich Raabe, Dimitri Papadopoulos, et d'autres cités dans le fichier NEWS. Merci de signaler les bogues à <distcc@lists.samba.org>.

LICENCE¶

L'utilisation de distcc est libre. Il ne peut être copié, modifié ou distribué que selon les termes de la licence publique générale GNU (GPL : « GNU General Public Licence »), version 2 ou suivantes. Une copie [NDT : en anglais] de cette licence est incluse dans le fichier COPYING.

VOIR AUSSI¶

distccd(1), ccache(1), gcc(1), make(1) http://distcc.samba.org/ http://ccache.samba.org/

TRADUCTION¶

Lionel Sausin. Merci aux participants de la liste « debian-l10n-french ».

AVERTISSEMENT SUR LA TRADUCTION¶

Il est possible que cette traduction soit imparfaite ou périmée. En cas de doute, veuillez vous reporter au document original en langue anglaise fourni avec le programme.